home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / zhsein.z / zhsein
Encoding:
Text File  |  2002-10-03  |  8.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. ZZZZHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          ZZZZHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ZHSEIN - use inverse iteration to find specified right and/or left
  10.      eigenvectors of a complex upper Hessenberg matrix H
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE ZHSEIN( SIDE, EIGSRC, INITV, SELECT, N, H, LDH, W, VL, LDVL,
  14.                         VR, LDVR, MM, M, WORK, RWORK, IFAILL, IFAILR, INFO )
  15.  
  16.          CHARACTER      EIGSRC, INITV, SIDE
  17.  
  18.          INTEGER        INFO, LDH, LDVL, LDVR, M, MM, N
  19.  
  20.          LOGICAL        SELECT( * )
  21.  
  22.          INTEGER        IFAILL( * ), IFAILR( * )
  23.  
  24.          DOUBLE         PRECISION RWORK( * )
  25.  
  26.          COMPLEX*16     H( LDH, * ), VL( LDVL, * ), VR( LDVR, * ), W( * ),
  27.                         WORK( * )
  28.  
  29. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  30.      These routines are part of the SCSL Scientific Library and can be loaded
  31.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  32.      directs the linker to use the multi-processor version of the library.
  33.  
  34.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  35.      4 bytes (32 bits). Another version of SCSL is available in which integers
  36.      are 8 bytes (64 bits).  This version allows the user access to larger
  37.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  38.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  39.      only one of the two versions; 4-byte integer and 8-byte integer library
  40.      calls cannot be mixed.
  41.  
  42. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  43.      ZHSEIN uses inverse iteration to find specified right and/or left
  44.      eigenvectors of a complex upper Hessenberg matrix H. The right
  45.      eigenvector x and the left eigenvector y of the matrix H corresponding to
  46.      an eigenvalue w are defined by:
  47.  
  48.                   H * x = w * x,     y**h * H = w * y**h
  49.  
  50.      where y**h denotes the conjugate transpose of the vector y.
  51.  
  52.  
  53. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  54.      SIDE    (input) CHARACTER*1
  55.              = 'R': compute right eigenvectors only;
  56.              = 'L': compute left eigenvectors only;
  57.              = 'B': compute both right and left eigenvectors.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ZZZZHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          ZZZZHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      EIGSRC  (input) CHARACTER*1
  75.              Specifies the source of eigenvalues supplied in W:
  76.              = 'Q': the eigenvalues were found using ZHSEQR; thus, if H has
  77.              zero subdiagonal elements, and so is block-triangular, then the
  78.              j-th eigenvalue can be assumed to be an eigenvalue of the block
  79.              containing the j-th row/column.  This property allows ZHSEIN to
  80.              perform inverse iteration on just one diagonal block.  = 'N': no
  81.              assumptions are made on the correspondence between eigenvalues
  82.              and diagonal blocks.  In this case, ZHSEIN must always perform
  83.              inverse iteration using the whole matrix H.
  84.  
  85.      INITV   (input) CHARACTER*1
  86.              = 'N': no initial vectors are supplied;
  87.              = 'U': user-supplied initial vectors are stored in the arrays VL
  88.              and/or VR.
  89.  
  90.      SELECT  (input) LOGICAL array, dimension (N)
  91.              Specifies the eigenvectors to be computed. To select the
  92.              eigenvector corresponding to the eigenvalue W(j), SELECT(j) must
  93.              be set to .TRUE..
  94.  
  95.      N       (input) INTEGER
  96.              The order of the matrix H.  N >= 0.
  97.  
  98.      H       (input) COMPLEX*16 array, dimension (LDH,N)
  99.              The upper Hessenberg matrix H.
  100.  
  101.      LDH     (input) INTEGER
  102.              The leading dimension of the array H.  LDH >= max(1,N).
  103.  
  104.      W       (input/output) COMPLEX*16 array, dimension (N)
  105.              On entry, the eigenvalues of H.  On exit, the real parts of W may
  106.              have been altered since close eigenvalues are perturbed slightly
  107.              in searching for independent eigenvectors.
  108.  
  109.      VL      (input/output) COMPLEX*16 array, dimension (LDVL,MM)
  110.              On entry, if INITV = 'U' and SIDE = 'L' or 'B', VL must contain
  111.              starting vectors for the inverse iteration for the left
  112.              eigenvectors; the starting vector for each eigenvector must be in
  113.              the same column in which the eigenvector will be stored.  On
  114.              exit, if SIDE = 'L' or 'B', the left eigenvectors specified by
  115.              SELECT will be stored consecutively in the columns of VL, in the
  116.              same order as their eigenvalues.  If SIDE = 'R', VL is not
  117.              referenced.
  118.  
  119.      LDVL    (input) INTEGER
  120.              The leading dimension of the array VL.  LDVL >= max(1,N) if SIDE
  121.              = 'L' or 'B'; LDVL >= 1 otherwise.
  122.  
  123.      VR      (input/output) COMPLEX*16 array, dimension (LDVR,MM)
  124.              On entry, if INITV = 'U' and SIDE = 'R' or 'B', VR must contain
  125.              starting vectors for the inverse iteration for the right
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ZZZZHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          ZZZZHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  137.  
  138.  
  139.  
  140.              eigenvectors; the starting vector for each eigenvector must be in
  141.              the same column in which the eigenvector will be stored.  On
  142.              exit, if SIDE = 'R' or 'B', the right eigenvectors specified by
  143.              SELECT will be stored consecutively in the columns of VR, in the
  144.              same order as their eigenvalues.  If SIDE = 'L', VR is not
  145.              referenced.
  146.  
  147.      LDVR    (input) INTEGER
  148.              The leading dimension of the array VR.  LDVR >= max(1,N) if SIDE
  149.              = 'R' or 'B'; LDVR >= 1 otherwise.
  150.  
  151.      MM      (input) INTEGER
  152.              The number of columns in the arrays VL and/or VR. MM >= M.
  153.  
  154.      M       (output) INTEGER
  155.              The number of columns in the arrays VL and/or VR required to
  156.              store the eigenvectors (= the number of .TRUE. elements in
  157.              SELECT).
  158.  
  159.      WORK    (workspace) COMPLEX*16 array, dimension (N*N)
  160.  
  161.      RWORK   (workspace) DOUBLE PRECISION array, dimension (N)
  162.  
  163.      IFAILL  (output) INTEGER array, dimension (MM)
  164.              If SIDE = 'L' or 'B', IFAILL(i) = j > 0 if the left eigenvector
  165.              in the i-th column of VL (corresponding to the eigenvalue w(j))
  166.              failed to converge; IFAILL(i) = 0 if the eigenvector converged
  167.              satisfactorily.  If SIDE = 'R', IFAILL is not referenced.
  168.  
  169.      IFAILR  (output) INTEGER array, dimension (MM)
  170.              If SIDE = 'R' or 'B', IFAILR(i) = j > 0 if the right eigenvector
  171.              in the i-th column of VR (corresponding to the eigenvalue w(j))
  172.              failed to converge; IFAILR(i) = 0 if the eigenvector converged
  173.              satisfactorily.  If SIDE = 'L', IFAILR is not referenced.
  174.  
  175.      INFO    (output) INTEGER
  176.              = 0:  successful exit
  177.              < 0:  if INFO = -i, the i-th argument had an illegal value
  178.              > 0:  if INFO = i, i is the number of eigenvectors which failed
  179.              to converge; see IFAILL and IFAILR for further details.
  180.  
  181. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  182.      Each eigenvector is normalized so that the element of largest magnitude
  183.      has magnitude 1; here the magnitude of a complex number (x,y) is taken to
  184.      be |x|+|y|.
  185.  
  186.  
  187. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  188.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ZZZZHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          ZZZZHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      This man page is available only online.
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.